/*----------------------------------------------------------
* FILE: DaoFinder.java
* LOGICAL NAME: DaoFinder
* PRODUCT: bila-framework
*----------------------------------------------------------
* MODIFICATIONS
* DATE Aug 25, 2011
* AUTHOR wjuarez
*----------------------------------------------------------
*/

package bila.framework.dao;

import java.io.Serializable;
import java.util.List;

/**
 * @author WJuarez
 * <b>Created by </b>wjuarez
 * <b>for</b> bila-framework
 * <b>package</b> bila.framework.dao
 * <b>on</b> Aug 25, 2011 11:10:54 PM
 * <b>Purpose</b> 
 * <p>
 *		DAO generico que posee metodos para realizar consultas de diferentes tipos
 * </p>
 */
public interface DaoFinder<Model, ModelId extends Serializable> {

	/**
	 * Metodo que realiza la busqueda ocupando
	 * como filtro todos los campos que no son nulos del objeto
	 * modelo que se pasa como parametro
	 * @param model objeto que posee los campos para filtro de busqueda
	 * @return objeto de tipo List<Model> con los registros que cumple la condicion de busqueda
	 * @throws Exception
	 */
	public List<Model> find(Model model) throws Exception;
	
	/**
	 * Metodo que busca un registro en especifico ocupando
	 * su llave primaria como parametros de busqueda
	 * @param model objeto que posee la llave primeria de la tabla
	 * @return objeto Model con la informacion del registro recuperado
	 * @throws Exception
	 */
	public Model findByKey(ModelId model) throws Exception;
	
	/**
	 * Metodo que recupera todos los registros de la tabla
	 * @return objeto de tipo List<Model> con los registros de la tabla
	 * @throws Exception
	 */
	public List<Model> getAll() throws Exception;
	
	/**
	 * Metodo que recupera informacion utilizando como filtro 
	 * los campos que no son de la llave ni que sean nulos del modelo
	 * @param model objeto de tipo Model con los parametros de busqueda
	 * @return objeto de tipo List<Model> con los registros recuperados
	 * @throws Exception
	 */
	public List<Model> getByExample(Model model) throws Exception;
	
	/**
	 * Metodo que realiza la busqueda utilizando la funcionalidad
	 * del metodo find de esta interfaz y ordenandolos segun el arreglo
	 * que se pasa como segundo parametro. Si el arreglo viene nulo
	 * no se ordena por ningun campo
	 * @param model objeto de tipo Model con los parametros de busqueda
	 * @param orders arreglo con los campos a utilizar para el ordenamiento
	 * @param orderType arreglo con el mismo numero del arreglo anterior que especifica
	 * 		  si el ordenamiento es ascendente o descendente
	 * @return objeto de tipo List<Model> con los registros recuperados
	 * @throws Exception
	 */
	public List<Model> findWithOrderBy(Model model, String[] orders, String[] orderType) throws Exception;
	
	/**
	 * Recupera todos los registros de la tabla ordenandolos
	 * por los parametros que se pasan como segundo parametro
	 * @param orders arreglo con los campos a utilizar para el ordenamiento
	 * @param orderType arreglo con el mismo numero del arreglo anterior que especifica
	 * 		  si el ordenamiento es ascendente o descendente
	 * @return objeto de tipo List<Model> con los registros recuperados
	 * @throws Exception
	 */
	public List<Model> getAllWithOrderBy(String[] orders, String[] orderType) throws Exception;
	
	/**
	 * Ejecuta un procedimiento almacenado de la base. Definiendo
	 * el nombre y la sententecia para invocar el procedimiento
	 * mas sus parametros
	 * @param sql nombre y definicion del procedimiento a utilizar
	 * @param params parametros del procedimiento almacenado
	 * @throws Exception
	 */
	public void executeProcedure(String sql, Object[] params) throws Exception;
	
	/**
	 * Ejecuta una funcion de la base de datos. Se debe definir
	 * el nombre de la funcion a utilizar mas sus parametros
	 * @param sql nombre y definicion de la funcion a utilizar
	 * @param params parametros de la funcion
	 * @return dependiendo de la funcion retorna un object de tipo 
	 * String, Integer, Float, Date, etc
	 * @throws Exception
	 */
	public Object executeFunction(String sql, Object[] params) throws Exception;
	
}
